/*
 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.util;

/**
 * <p>这个类提供了Collection的一个骨骼似的实现，来最小化实现这个接口需要的工作。
 * 
 * <p>为了实现一个不可更改的collection，编程者仅仅需要扩展这个类，并提供iteratro和size方法的实现。
 * （iterator方法返回的iterator必须实现hasNext和next方法）
 * 
 * <p>为了实现一个可变的colletion，编程者必须额外地覆盖这个类的add方法（否则抛出UnsupportedOperationException），
 * iterator方法返回的iterator必须额外地实现remove方法。
 * 
 * <p>编程者必须通常提供一个无参的Collection构造器，这是Collection接口的推荐规范。
 * 
 * <p>这个类的每个非抽象方法的文档仔细地描述了它的实现。
 * 这些方法的每一个可以被覆盖，如果被实现的集合需要一个更高效的实现。
 *
 *
 * @author  Josh Bloch
 * @author  Neal Gafter
 * @see Collection
 * @since 1.2
 */

public abstract class AbstractCollection<E> implements Collection<E> {
    /**
     * 唯一的构造器（为了子类构造器的调用，通常是暗示的）
     */
    protected AbstractCollection() {
    }

    // Query Operations

    /**
     * Returns an iterator over the elements contained in this collection.
     *
     * @return an iterator over the elements contained in this collection
     */
    public abstract Iterator<E> iterator();

    public abstract int size();

    /**
     * {@inheritDoc}
     *
     * <p>通过size的返回值是否为0，判断是否为空
     */
    public boolean isEmpty() {
    	//通过size的返回值是否为0，判断是否为空
        return size() == 0;
    }

    /**
     * {@inheritDoc}
     *
     * <p>这个实现遍历集合中每个元素，检查每个元素，是否与指定元素相同。
     *
     * @throws ClassCastException   {@inheritDoc}
     * @throws NullPointerException {@inheritDoc}
     */
    public boolean contains(Object o) {
        Iterator<E> it = iterator();
        if (o==null) {
            while (it.hasNext())
                if (it.next()==null)
                	//如果o为null，则iterator中有一个为null，返回true
                    return true;
        } else {
            while (it.hasNext())
                if (o.equals(it.next()))
                	//o不为null，iterator遍历中，有一个与它equals，返回true
                    return true;
        }
        return false;
    }

    /**
     * {@inheritDoc}
     *
     * <p>这个实现返回一个包含由这个集合的iterator包含的所有元素的数组，
     * 以相同的顺序，存在数组中连续的元素中，起始index为0.
     * 返回的数组的长度与iterator返回的元素的数量相同，即使在遍历期间，集合改变，
     * 就像集合允许在遍历中，发生并发的修改。
     * size方法仅仅因为优化，提示调用。即使iterator返回不同数量的元素，也会返回正确的结果。
     *
     * <p>方法与下面相同
     *
     *  <pre> {@code
     * List<E> list = new ArrayList<E>(size());
     * for (E e : this)
     *     list.add(e);
     * return list.toArray();
     * }</pre>
     */
    public Object[] toArray() {
    	//数组大小预估为size，准备好遇到更多或者更少的元素
        Object[] r = new Object[size()];
        Iterator<E> it = iterator();
        for (int i = 0; i < r.length; i++) {
            if (! it.hasNext()) // 比预期遇到的元素更少
                return Arrays.copyOf(r, i);  //将r中的前i个元素，复制到一个新数组
            r[i] = it.next();
        }
        return it.hasNext() ? finishToArray(r, it) : r; //如果没有next了，直接返回r，否则调用finishToArray
    }

    /**
     * {@inheritDoc}
     *
     * <p>
     * 这个实现返回一个包含由这个集合的iterator包含的所有元素的数组，
     * 以相同的顺序，存在数组中连续的元素中，起始index为0.
     * 如果iterator返回的元素数量对于制定数组过多，返回的元素，会在一个新分配的数组，
     * 长度与iterator返回的元素数量相同，即使在迭代中集合的大小改变，这可能当集合在迭代中允许并发修改时发生。
     * size方法仅仅因为优化，提示调用。即使iterator返回不同数量的元素，也会返回正确的结果。
     *
     * <p>方法与下面等同：
     *
     *  <pre> {@code
     * List<E> list = new ArrayList<E>(size());
     * for (E e : this)
     *     list.add(e);
     * return list.toArray(a);
     * }</pre>
     *
     * @throws ArrayStoreException  {@inheritDoc}
     * @throws NullPointerException {@inheritDoc}
     */
    @SuppressWarnings("unchecked")
    public <T> T[] toArray(T[] a) {
        // Estimate size of array; be prepared to see more or fewer elements
        int size = size();
        //如果size大于a的长度，则新分配size大小的数组给a
        T[] r = a.length >= size ? a :
                  (T[])java.lang.reflect.Array
                  .newInstance(a.getClass().getComponentType(), size);
        Iterator<E> it = iterator();

        for (int i = 0; i < r.length; i++) {
            if (! it.hasNext()) { // fewer elements than expected
                if (a == r) {
                    r[i] = null; // null-terminate
                } else if (a.length < i) {
                    return Arrays.copyOf(r, i);
                } else {
                    System.arraycopy(r, 0, a, 0, i);
                    if (a.length > i) {
                        a[i] = null;
                    }
                }
                return a;
            }
            r[i] = (T)it.next();
        }
        // more elements than expected
        return it.hasNext() ? finishToArray(r, it) : r;
    }

    /**
     * 数组分配的最大长度。
     * 一些vm在数组中保留一些头信息。试图分配更大的数组可能会导致OutOfMemoryError:请求的数组大小超过VM限制
     * 
     */
    private static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8;

    /**
     * 重新分配数组的空间，当iterator返回超过预期的元素。以从iterator的元素填满结束。
     *
     * @param r the array, replete with previously stored elements
     * @param it the in-progress iterator over this collection
     * @return array containing the elements in the given array, plus any
     *         further elements returned by the iterator, trimmed to size
     */
    @SuppressWarnings("unchecked")
    private static <T> T[] finishToArray(T[] r, Iterator<?> it) {
        int i = r.length; //i为传入数组的长度
        while (it.hasNext()) {  //当it有更多的元素
            int cap = r.length;  //cap为数组当前长度
            if (i == cap) {  //如果相同，填入不进新的元素
                int newCap = cap + (cap >> 1) + 1;  //新长度为1.5倍的原长度+1
                // overflow-conscious code
                if (newCap - MAX_ARRAY_SIZE > 0)  //如果新长度>MAX_ARRAY_SIZE,则为 Integer.MAX_VALUE 
                    newCap = hugeCapacity(cap + 1);
                r = Arrays.copyOf(r, newCap);  //将原来数组拷贝到长度为newCap的新数组
            }
            r[i++] = (T)it.next();  //放入新元素
        }
        // trim if overallocated
        return (i == r.length) ? r : Arrays.copyOf(r, i);  //将多余的空格删掉，放入一个适应大小的数组
    }

    private static int hugeCapacity(int minCapacity) {
        if (minCapacity < 0) // overflow
            throw new OutOfMemoryError
                ("Required array size too large");
        return (minCapacity > MAX_ARRAY_SIZE) ?
            Integer.MAX_VALUE :
            MAX_ARRAY_SIZE;
    }

    // Modification Operations

    /**
     * {@inheritDoc}
     *
     * <p>This implementation always throws an
     * <tt>UnsupportedOperationException</tt>.
     *
     * @throws UnsupportedOperationException {@inheritDoc}
     * @throws ClassCastException            {@inheritDoc}
     * @throws NullPointerException          {@inheritDoc}
     * @throws IllegalArgumentException      {@inheritDoc}
     * @throws IllegalStateException         {@inheritDoc}
     */
    public boolean add(E e) {
        throw new UnsupportedOperationException();
    }

    /**
     * {@inheritDoc}
     *
     * <p>这个实现迭代了集合，寻找指定元素。如果找到这个元素，使用iterator的remove方法，
     * 从集合中移除这个元素。
     *
     * <p>注意：这个实现会抛出UnsupportedOperationException，如果iterator没有实现remove方法，
     * 并且之歌集合包含了指定的元素。
     *
     * @throws UnsupportedOperationException {@inheritDoc}
     * @throws ClassCastException            {@inheritDoc}
     * @throws NullPointerException          {@inheritDoc}
     */
    public boolean remove(Object o) {
        Iterator<E> it = iterator();
        if (o==null) {
            while (it.hasNext()) {
                if (it.next()==null) {
                    it.remove();
                    return true;
                }
            }
        } else {
            while (it.hasNext()) {
                if (o.equals(it.next())) {
                	//找到了就删除
                    it.remove();
                    return true;
                }
            }
        }
        return false;
    }


    // Bulk Operations

    /**
     * {@inheritDoc}
     *
     * <p>这个实现迭代指定的集合，检查iterator返回的每个元素，来看它是否在其中。
     * 只有所有的元素都被包含，返回true，否则返回false
     *
     * @throws ClassCastException            {@inheritDoc}
     * @throws NullPointerException          {@inheritDoc}
     * @see #contains(Object)
     */
    public boolean containsAll(Collection<?> c) {
        for (Object e : c)
        	//调用c的迭代器
        	//iterator迭代，有一个没找到，就返回false
            if (!contains(e))
                return false;
        return true;
    }

    /**
     * {@inheritDoc}
     *
     * <p>这个实现迭代了指定集合，将迭代器返回的每个对象加入到这个集合。
     *
     * <p>注意：这个实现将抛出UnsupportedOperationException，除非add被覆盖了（假设指定结合非空）
     *
     * @throws UnsupportedOperationException {@inheritDoc}
     * @throws ClassCastException            {@inheritDoc}
     * @throws NullPointerException          {@inheritDoc}
     * @throws IllegalArgumentException      {@inheritDoc}
     * @throws IllegalStateException         {@inheritDoc}
     *
     * @see #add(Object)
     */
    public boolean addAll(Collection<? extends E> c) {
        boolean modified = false;
        for (E e : c)
        	//调用c的迭代器
            if (add(e))
            	//有一个被加入了，就返回true
                modified = true;
        return modified;
    }

    /**
     * {@inheritDoc}
     *
     * <p>这个实现迭代这个集合，检查iterator返回的每个元素，来看它是否包含在指定集合。
     * 如果被包含，通过iterator的remove方法移除这个元素
     *
     * <p>注意：这个实现将抛出UnsupportedOperationException，如果iterator没有实现remove方法，
     * 同时这个集合与指定集合包含一个或多个相同的元素。
     *
     * @throws UnsupportedOperationException {@inheritDoc}
     * @throws ClassCastException            {@inheritDoc}
     * @throws NullPointerException          {@inheritDoc}
     *
     * @see #remove(Object)
     * @see #contains(Object)
     */
    public boolean removeAll(Collection<?> c) {
        Objects.requireNonNull(c);
        boolean modified = false;
        //调用自己的迭代器
        Iterator<?> it = iterator();
        while (it.hasNext()) {
            if (c.contains(it.next())) {
                it.remove();
                modified = true;
            }
        }
        return modified;
    }

    /**
     * {@inheritDoc}
     *
     * <p>这个实现迭代这个集合，检查iterator返回的每个元素，来看是否包含在指定集合中。
     * 如果不被包含，调用iterator的remove方法，将元素从这个集合中移除。
     *
     * <p>注意：这个实现将抛出UnsupportedOperationException，如果iterator没有实现remove方法，
     * 同时这个集合包含一个或多个不存在于指定集合的元素。
     *
     * @throws UnsupportedOperationException {@inheritDoc}
     * @throws ClassCastException            {@inheritDoc}
     * @throws NullPointerException          {@inheritDoc}
     *
     * @see #remove(Object)
     * @see #contains(Object)
     */
    public boolean retainAll(Collection<?> c) {
        Objects.requireNonNull(c);
        boolean modified = false;
        //调用自己的iterator
        Iterator<E> it = iterator();
        while (it.hasNext()) {
            if (!c.contains(it.next())) {
                it.remove();
                modified = true;
            }
        }
        return modified;
    }

    /**
     * {@inheritDoc}
     *
     * <p>这个实现迭代这个集合，使用iterator的remove方法，移除每个元素。
     * 绝大多数实现很可能为了效率，覆盖这个方法。
     *
     * <p>注意：这个实现将抛出UnsupportedOperationException，如果iterator没有实现remove方法，
     * 而且集合非空
     *
     * @throws UnsupportedOperationException {@inheritDoc}
     */
    public void clear() {
        Iterator<E> it = iterator();
        while (it.hasNext()) {
            it.next();
            it.remove();
        }
    }


    //  String conversion

    /**
     * 返回这个集合的字符串表示。字符串表示有集合的元素构成，顺序为iterator返回的顺序，以方括号[]包围。
     * 相邻的两个元素以逗号和空格, 分割。元素通过String.valueOf(Object)被转为字符串。
     *
     * @return a string representation of this collection
     */
    public String toString() {
        Iterator<E> it = iterator();
        if (! it.hasNext())
        	//空的情况
            return "[]";

        StringBuilder sb = new StringBuilder();
        sb.append('[');
        for (;;) {
            E e = it.next();
            //内部为 append(String.valueOf(obj))
            sb.append(e == this ? "(this Collection)" : e);
            if (! it.hasNext())
            	//结束
                return sb.append(']').toString();
            //加逗号，加空格
            sb.append(',').append(' ');
        }
    }

}
